<html>
<!-- 
$Id$
------------------------------------------------------------------------
 The documentation file for the Virtual Geometry Model
 Copyright (C) 2007, 2014 Ivana Hrivnacova               
 All rights reserved. 
           
 For the licensing terms see vgm/LICENSE.
 Contact: ivana@ipno.in2p3.fr
------------------------------------------------------------------------
-->

<head><title>Virtual Geometry Model</title></head><body bgcolor="white" text="black">
<basefont face="verdana,arial,helvetica,sans-serif">

 <h1> Virtual Geometry Model </h1>

<p>
<b> Virtual Geometry Model (VGM) </b>  is a geometry conversion tool, actually providing 
conversion between Geant4 and ROOT TGeo geometry models. Its design allows inclusion of 
another geometry model  by implementing a single sub-module instead of writing bilateral
converters for all already supported models. </p>
<p>
The reference paper: <i> <a href="http://iopscience.iop.org/article/10.1088/1742-6596/119/4/042016/pdf">
I. Hrivnacova et al 2008 J. Phys.: Conf. Ser. 119 042016 </a></i>.
</p>

 <ul><li><a href="#Introduction">        Introduction</a>
     <li><a href="#Download">            Download</a>
     <li><a href="#Installation">        Installation, Examples</a>
     <li><a href="#GeometryConversions"> Geometry conversions</a>
     <li><a href="#GeometryConstruction">Geometry construction via VGM</a>
     <li><a href="#XML">                 XML</a>
     <li><a href="#Options">             Options</a>
     <li><a href="#Documentation">       Source code documentation</a>
     <li><a href="#Platforms">           Platforms</a>
     <li><a href="#Publications">        Publications</a>
 </ul>
    
 <a name="Introduction"></a> 
 <h2> Introduction </h2>

 <p>  
 The Virtual Geometry Model (VGM) has been developed as a generalization
 of the existing convertors roottog4, g4toxml provided within 
 <a href="http://root.cern.ch/root/vmc/Geant4VMC.html"> Geant4 VMC </a>,
 when new directions: g4toroot, roottoxml were asked by users.
 Instead of adding other bilateral converters and multiplying
 the implementations, the abstract layer to geometry has been defined
 and the geometry models have been "mapped" to this generalized
 scheme. Once this is done, the geometry objects in different models 
 can be handled in the same way.
 
 <p>  
 In the VGM, abstract interfaces to geometry objects 
 and an abstract factory for geometry construction, import and export are 
 introduced. The interfaces to geometry objects were defined with the intention
 to be suitable for desription of "geant-like" geometries with a hierarchical volume
 structure.

 <p>
 The implementation of the VGM for a concrete geometry model represents
 a layer between the VGM and the particular native geometry.
 At present  this implementation is provided for the 
 <a href="http://wwwasd.web.cern.ch/wwwasd/geant4/geant4.html"> Geant4 </a>, 
 and <a href="http://root.cern.ch"> Root TGeo </a>  
 geometry models.

 <p>
 Using the VGM factory, geometry can first be defined independently from
 a concrete geometry model, and then built by choosing a concrete
 instantiation of it. Alternatively, the import function of the VGM factory
 makes it possible to use VGM directly with native geometries (Geant4,
 TGeo). The export functions provide conversion into other native 
 geometries or the XML format.

 <p>
 To port a new geometry model, then providing the VGM layer for it is 
 sufficient to obtain all the converters between this third geometry and 
 already ported geometries (Geant4, Root, XML AGDD, GDML).

 <a name="Download"></a> 
 <h2> Download </h2>

 <p> 
 
 <h3> GitHub: </h3>
 
 <p>
 Development version (the whole repository): <br>
 <font color="#ff0000" face="Bookman Old Style">
 git clone http://github.com/vmc-project/vgm.git
 </font><br>
 <i> Tested with Root 6.18/04, Geant4 10.06.p01
    (with embedded CLHEP 2.4.1.3)</i>
 
 <p>
 To switch to the last tagged version (4.8): <br>
 <font color="#ff0000" face="Bookman Old Style">
 cd vgm <br>
 git checkout v4-8
 </font><br>
 <i> Tested with Root 6.18/04, Geant4 10.06.p01
    (with embedded CLHEP 2.4.1.3) </i>
 
 <p>
 See also a description of changes in the 
 <a href="VGMhistory.txt"> history </a>  
 file, previous version(s) are available from
 <a href="http://github.com/vmc-project/vgm.git"> GitHub</a>.


 <a name="Installation"></a> 
 <h2> Installation, Examples </h2>
 
 <p>
 Since version 4.0, only <a href="http://www.cmake.org/"> CMake </a> 
 build system is supported. 
 The installation and testing procedures for this system are described in detail 
 in vgm/doc/INSTALL.

 <p>
 The <a href="http://www.cmtsite.org/"> CMT </a> and 
 <a href="http://www.gnu.org/software/autoconf/"> Autoconf </a> 
 build systems are removed (for maintenance reasons)
 and <a href="http://www.gnu.org/software/make/">, GNUmake </a> build system 
 is temporarily kept as deprecated.

 <p>
 As the test program (being written for the purpose of testing of all
 features) is too complex, four simple examples demonstrating use
 of VGM for converting native geometries are provided in vgm/examples.
 The instructions how to build and run these examples are included
 in the README file in each example.

 <a name="GeometryConversions"></a> 
 <h2> Geometry conversions </h2>

 <p>
 To convert native geometry from one geometry model to another,
 the geometry has to be first imported in the VGM (the native geometry 
 objects are mapped to the VGM interfaces) using the concrete VGM factory 
 for this geometry model, and then exported using the VGM factory for 
 the other geometry model.
 
 <p>
 To convert Geant4 geometry in Root:
 <pre>                                                  <font face="Courier" color="#00aa00">
 #include "Geant4GM/volumes/Factory.h" 
 #include "RootGM/volumes/Factory.h" 
 #include "TGeoManager.h"                               
                                                        <font color="#aa00ff"><I>
 // Import Geant4 geometry to VGM                       </I></font>
 Geant4GM::Factory g4Factory;
 g4Factory.Import(physiWorld);                          <font color="#aa00ff"><I>
      // where physiWorld is of G4VPhysicalVolume* type </I></font><font color="#aa00ff"><I>

 // Export VGM geometry to Root                         </I></font>
 RootGM::Factory rtFactory;
 g4Factory.Export(&rtFactory);
 gGeoManager->CloseGeometry();
 return rtFactory.World();                              <font color="#aa00ff"><I>
      // returns Root top node, of TGeoNode* type       </I></font></font>
 </pre>
      
 <p>
 The geometry conversions between Geant4 and Root
 geometry models are demonstrated in provided examples E01 and E02.

 <p>
 Since version 4.4, it is also to use VGM to convert a single solid from one geometry
 model into another one:                                <font face="Courier" color="#00aa00">
<pre>
  XFactory xFactory;
  YFactory yFactory;
  xFactory.Import(xsolid);
  xFactory.Export(yFactory);
  YSolid* ysolid = yFactory.Solid();                    </font>
</pre>
 
 <a name="GeometryConstruction"></a> 
 <h2> Geometry construction via VGM </h2>

 <p>
 The VGM interfaces can be used to define geometry independently
 from a concrete geometry model. <br>
 For example, the code below builds a world box volume:

 <pre>                                                    <font face="Courier" color="#00aa00">
 #include "VGM/volumes/IFactory.h"
 #include "ClhepVGM/transform.h"
 using namespace VGM;

 MyDetectorConstruction::Construct(VGM::IFactory* factory)
 {                                                    
   double wSize = 10*m;
   GISolid* worldS
     = factory->CreateBox("worldS", wSize, wSize, wSize); <font color="#aa00ff"><I>
                // create the world solid                 </font></I>		

   GIVolume* worldV
     = factory->CreateVolume("worldV", worldS, "Air");    <font color="#aa00ff"><I>
                // create the world volume                </font></I>

   factory->CreatePlacement("world", 0, worldV, 0, ClhepVGM::Identity());<font color="#aa00ff"><I>
                // place the world volume                 </font></I></font>
 }    
 </pre>
 
 Choosing the concrete factory (Geant4 or Root VGM factory)
 will then build the geometry of the chosen model ( Geant4 or Root):

 <pre>                                                    <font face="Courier" color="#00aa00">
 #include "Geant4GM/volumes/Factory.h"
 MyDetectorConstruction myDetectorConstruction;
 Geant4GM::Factory theFactory;
 myDetectorConstruction->Construct(&theFactory);          <font color="#aa00ff"><I>
         // Geant4 geometry will be built                 </font></I>	
 
 #include "RootGM/volumes/Factory.h"
 MyDetectorConstruction myDetectorConstruction;
 RootGM::Factory theFactory;
 myDetectorConstruction->Construct(&theFactory);          <font color="#aa00ff"><I>
         // Root geometry will be built                   </font></I></font>
 </pre>
 
 <a name="XML"></a> 
 <h2> XML </h2>

 <p>
 The VGM geometry can be exported to XML in the AGDD or 
 <a href="http://gdml.web.cern.ch/gdml"> GDML </a> 
 format.
 The complying with the XML schema is embedded in the VGM XML exporter
 code itself, no external XML parser is then needed.

 <pre>                                                    <font face="Courier" color="#00aa00">
 #include "XmlVGM/AGDDExporter.h"
 XmlVGM::AGDDExporter xmlExporter1(&theFactory);
 xmlExporter1.GenerateXMLGeometry();                      <font color="#aa00ff"><I>
      // Export geometry to AGDD                          </font></I> 
                                                        
 #include "XmlVGM/GDMLExporter.h"
 XmlVGM::GDMLExporter xmlExporter2(&theFactory);
 xmlExporter2.GenerateXMLGeometry();                      <font color="#aa00ff"><I> 
      // Export geometry to GDML                          </font></I></font>
 </pre>
  
 The export from native geometries (Geant4, Root) to XML
 is demonstrated in examples E03 and E04.
 The exported XML files (both AGDD and GDML) can be then viewed
 with the 
  <a href="http://hrivnac.home.cern.ch/hrivnac/Activities/Packages/GraXML">
 GraXML tool </a>.

 </p>

 <a name="Options"></a> 
 <h2> Options </h2>
 
 <h3> Debug </h3>
 
 <p>
 Debug printing can be switched on via VGM::IFactory::SetDebug function:
 
 <pre>                                                    <font face="Courier" color="#00aa00">
 IFactory& myFactory;                                     
 myFactory.SetDebug(n);                                   </font><font color="#aa00ff"><I>
      // where n=1 or 2; if 2 also object adresses are printed  </font></I>
 </pre>
 </p>
 
 <h3> Ignore </h3> 
 
 <p>
 If geometry imported in VGM includes some solid not supported
 in VGM (eg. a user defined solid in Geant4), then VGM prints a warning 
 and stops. It is however possible to let VGM continue by setting the option
 "Ignore" to the factory importing the geometry:

 <pre>                                                    <font face="Courier" color="#00aa00">
 IFactory& myFactory;                                     
 myFactory.SetIgnore(true);                               </font>
 </pre>
 </p>

 <h3> BestMatch  </h3>

 <p>
 This option is used only in the context of a division with gaps in Root geometry. As there is not an equivalent placement in Root, this feature is emulated by default via an intermediate division without gaps and a placement of the cell volumes. This however results in a different volume hierarchy than in the source (Geant4 geometry).

 <p>
 When a new, "bestMatch" option is selected, this feature is implemented via simple placements of the cells in the mother volume, what may be however ineffiecient in case of a large number of divisions.

 <pre>                                                    <font face="Courier" color="#00aa00">
 IFactory& myFactory;
 myFactory.SetBestMatch(true);                            </font>
 </pre>
 </p>

 <a name="Documentation"></a> 
 <h2> Source code documentation </h2>

 <a href="http://ivana.home.cern.ch/ivana/vgm_html/index.html">
 Source code documentation </a>
 has been generated from the source code by 
 <a href="http://www.stack.nl/%7Edimitri/doxygen//index.html">
 Doxygen </a>.

</p>

 <a name="Platforms"></a> 
 <h2> Platforms </h2>

<p>
 Tested platform: Mac OSX 10.14: with Apple LLVM version 10.0.0

<hr>

<a name="Publications"></a> 
<h2> Publications </h2>
<ul>
<li> <a href="http://iopscience.iop.org/article/10.1088/1742-6596/119/4/042016/pdf">
I. Hrivnacova et al 2008 J. Phys.: Conf. Ser. 119 042016 </a></i></li>
<li> <a href="http://indico.cern.ch/event/0/contributions/1294400/">
I. Hrivnacova 2004 Computing in High Energy and Nuclear Physics (Interlaken) Id 387 </a></i>. </li>
</ul>

<p>
Contact: <br>
Ivana Hrivnacova, IPN Orsay <a href="mailto:ivana@ipno.in2p3.fr"> ivana@ipno.in2p3.fr </a> <br>

<p>
<i> Last update: 28/02/2020 </i>

</p></body></html>
